Fix factual and spec errors in docs content by externl · Pull Request #521 · icerpc/icerpc-docs

externl · 2026-07-08T14:37:46Z

Fixes ~35 factual errors across 25 content pages, found during a full editorial review. Every claim was verified against slicec 0.4.0 (the version icerpc-csharp 0.6 pins), the icerpc-csharp generators, or recomputed by hand.

Slice encoding

user-defined-types.md — the worked example encoded tag 2 as 0x10; a varint32 of 2 on 1 byte is 0x08
icerpc.md — the stream argument / stream return value pairing was swapped between outgoing request and response
primitive-types.md — varuint62 vs QUIC: byte order is not the only difference; QUIC stores the 2-bit length in the most significant bits of the first byte, Slice in the least significant bits

Slice grammar reference (brought back in sync with slicec 0.4.0)

Enum production gains "compact"? — placed before "unchecked"?, matching the parser
Enumerator production gains the variant field list ("(" UndelimitedList<Field> ")")?
FileAttribute/LocalAttribute now use the bracket tokens ([[ ]] / [ ]) instead of nonexistent/wrong brace tokens
removed the stale FileCompilationMode production and its SliceFilePrelude alternatives — the mode statement no longer exists in slicec 0.4.0 (it referenced a mode_keyword token that was never defined anyway)
removed CompactId (referenced by nothing) and ThrowsBlock/throws_keyword (slicec has no @throws)
renamed the preprocessor lexical token to undefine_keyword to match the syntactic grammar
prose: fields can also appear in enumerators, doc comments on parameters are forbidden, tag numbers are non-negative, and 0x_ab_cd_ef is 0xabcdef

Language guide & basics

DefaultServicePath sample → "/Example.Widget" (:: → ., per the generator)
block comments do not nest
only basic enums (with an underlying type) can be dictionary keys
reworked the circular-import example in slice-files.md — it used invalid syntax (Egg lay()) and interfaces as return types; the two files now exchange structs
"two built-in generic types" → three (adds Result)
doc-comment examples: removed the nonexistent @param color and stopped returning interface Widget directly
cs::encodeReturn → cs::encodedReturn (per the generator source)
the sequence fast path covers fixed-size numeric (not just integral) types
the Slic Version frame carries varuint62 (not varint62) values

Getting started (0.6 template drift)

contract paths → slice/VisitorCenter/Greeter.slice and proto/visitor_center/greeter.proto (matching the 0.6 templates and the pages' own screenshots)
--transport is only defined by the non-DI templates
Slice compilation produces generated/Greeter.cs and generated/Greeter.IceRpc.cs
the Slice server tutorial now covers Program.Authentication.cs like its three sibling tutorials

Misc

un-merged two accidentally joined bullets on the DI page
dropped the outdated "a priority queue … is not a standard C# container" claim (PriorityQueue<TElement, TPriority> exists since .NET 6)
proxies are "concrete types" (record structs), modules also scope interfaces, "proxy" → "client" in the Protobuf tutorial, and a comment for the CancelKeyPressed helper

Deliberate skip: the source_block; notation nit — the existing comment in the grammar already explains it.

🤖 Generated with Claude Code

Copilot

Pull request overview

This PR updates the documentation set to correct a broad set of factual/spec mismatches (Slice grammar reference, encoding examples, and getting-started/tutorial content) so the published docs align with actual slicec parsing behavior, generator outputs, and on-the-wire encoding.

Changes:

Sync Slice grammar reference pages with slicec behavior (enum modifiers/grammar productions, attribute tokens, token naming).
Fix Slice encoding documentation inaccuracies (tag example byte, varuint62 vs QUIC details, request/response stream continuation description).
Update getting-started tutorials and other guides for template drift, naming, and corrected examples.

Reviewed changes

Copilot reviewed 25 out of 25 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
content/slice/language-reference/slice-grammar.md	Align grammar + prose with slicec (enum/attributes/tokens) and fix several factual notes/examples.
content/slice/language-reference/preprocessor-directives.md	Rename the `#undef` token name to match the syntactic grammar.
content/slice/language-reference/doc-comments.md	Remove unsupported `@throws` grammar elements.
content/slice/language-guide/sequence-types.md	Correct C# fast-path wording to “fixed-size numeric” types.
content/slice/language-guide/operation.md	Fix `cs::encodedReturn` attribute name and grammar in prose.
content/slice/language-guide/module.md	Clarify that modules scope interfaces as well as types.
content/slice/language-guide/interface.md	Correct wording around proxies and fix `DefaultServicePath` example.
content/slice/language-guide/dictionary-types.md	Clarify dictionary key constraints (basic enums).
content/slice/language-guide/comments.md	Correct block comment nesting claim and doc-comment example signatures.
content/slice/language-guide/attributes.md	Fix `cs::encodedReturn` attribute name in the attribute table.
content/slice/index.md	Update built-in generic types count and add `Result` link.
content/slice/encoding/user-defined-types.md	Fix tagged-field worked example (tag byte).
content/slice/encoding/primitive-types.md	Correct varuint62 vs QUIC comparison details.
content/slice/encoding/icerpc.md	Fix request/response stream continuation pairing description.
content/slice/basics/slice-files.md	Replace invalid circular-reference example with valid cross-file struct/interface usage.
content/slice/basics/examples.md	Remove nonexistent doc-comment `@param color` in example.
content/icerpc/slic-transport/protocol-frames.md	Fix `Version` frame value type name (`varuint62`).
content/icerpc/dependency-injection/di-and-icerpc-for-csharp.md	Split/clarify accidentally merged DI bullet list.
content/icerpc-for-ice-users/rpc-core/object-adapter.md	Clarify what `CancelKeyPressed` represents in the snippet.
content/icerpc-for-ice-users/ice-definitions/sequence-types.md	Remove outdated claim about priority queue availability in .NET.
content/getting-started/installation/template.md	Clarify `--transport` support scope (non-DI templates).
content/getting-started/icerpc-slice-tutorial/server-tutorial.md	Update template paths/output files and document `Program.Authentication.cs`.
content/getting-started/icerpc-slice-tutorial/client-tutorial.md	Update template paths and generated output files.
content/getting-started/icerpc-protobuf-tutorial/server-tutorial.md	Update proto contract path to match templates.
content/getting-started/icerpc-protobuf-tutorial/client-tutorial.md	Update proto contract path and “proxy” → “client” wording.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

externl · 2026-07-08T15:17:05Z

+Tags consist of the `tag` keyword, followed by a non-negative integer wrapped in a pair of parentheses.
 This integer must be between `0` and `2,147,483,647` (the maximum value of a signed 32-bit integer).
 Tags can only be applied to [fields][field] and [parameters][parameter] with an optional type.


This matches slicec's actual parser: the Tag rule in grammar.lalrpop is tag_keyword "(" SignedInteger ")" (same on 0.6-era v0.3.3), and parse_tag_value rejects negatives afterwards as a semantic error. The grammar production is faithful to the parser; "non-negative" (like the 2,147,483,647 max on the next line) is a semantic constraint the grammar deliberately doesn't encode. Keeping SignedInteger.

Correction on the version cited here: icerpc-csharp 0.6 pins slicec 0.4.0, not 0.3.x — the Tag rule is identical there (tag_keyword "(" SignedInteger ")" with parse_tag_value rejecting negatives), so the conclusion stands.

externl · 2026-07-08T15:17:06Z

    : tag_keyword left_parenthesis SignedInteger right_parenthesis
    ;


Same as the section grammar: slicec's parser really does accept a SignedInteger here and rejects negative values during validation, so the production matches the parser. Keeping SignedInteger.

Same correction as above: verified against slicec 0.4.0 (what 0.6 pins) — identical rule, conclusion stands.

bernardnormier

Looks good.

bernardnormier · 2026-07-08T17:06:40Z


-interface Chicken {
-   Egg lay()
+struct Chicken {


This is a good fix. The previous example relied on proxy custom types (with the custom not shown), which was confusing.

Co-authored-by: Austin Henriksen <austin.r.henriksen79@gmail.com>

Fix factual and spec errors in docs content

b4b7f60

Copilot AI review requested due to automatic review settings July 8, 2026 14:37

Copilot started reviewing on behalf of externl July 8, 2026 14:38 View session

externl requested a review from InsertCreativityHere July 8, 2026 14:39

Copilot AI reviewed Jul 8, 2026

View reviewed changes

externl requested a review from bernardnormier July 8, 2026 14:44

Remove FileCompilationMode from the Slice grammar

1d80153

bernardnormier approved these changes Jul 8, 2026

View reviewed changes

InsertCreativityHere reviewed Jul 9, 2026

View reviewed changes

externl and others added 7 commits July 20, 2026 08:52

Update content/slice/language-guide/operation.md

2ce0c23

Co-authored-by: Austin Henriksen <austin.r.henriksen79@gmail.com>

Update content/slice/language-guide/sequence-types.md

85ece5c

Co-authored-by: Austin Henriksen <austin.r.henriksen79@gmail.com>

Update content/slice/index.md

a9034bf

Co-authored-by: Austin Henriksen <austin.r.henriksen79@gmail.com>

Update content/slice/language-guide/comments.md

002ec47

Co-authored-by: Austin Henriksen <austin.r.henriksen79@gmail.com>

Update content/slice/language-guide/comments.md

0dd98b9

Co-authored-by: Austin Henriksen <austin.r.henriksen79@gmail.com>

Update content/slice/language-guide/comments.md

767fed0

Co-authored-by: Austin Henriksen <austin.r.henriksen79@gmail.com>

Update content/slice/language-guide/comments.md

a3280a9

Co-authored-by: Austin Henriksen <austin.r.henriksen79@gmail.com>

externl merged commit 4c82bef into icerpc:main Jul 20, 2026
9 checks passed

externl deleted the fix-content-spec branch July 20, 2026 14:18

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Fix factual and spec errors in docs content - #521

Fix factual and spec errors in docs content#521
externl merged 9 commits into
icerpc:mainfrom
externl:fix-content-spec

externl commented Jul 8, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

externl Jul 8, 2026

Uh oh!

externl Jul 8, 2026

Uh oh!

externl Jul 8, 2026

Uh oh!

externl Jul 8, 2026

Uh oh!

bernardnormier left a comment

Uh oh!

bernardnormier Jul 8, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

		: tag_keyword left_parenthesis SignedInteger right_parenthesis
		;

Uh oh!

Conversation

externl commented Jul 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

externl Jul 8, 2026

Choose a reason for hiding this comment

Uh oh!

externl Jul 8, 2026

Choose a reason for hiding this comment

Uh oh!

externl Jul 8, 2026

Choose a reason for hiding this comment

Uh oh!

externl Jul 8, 2026

Choose a reason for hiding this comment

Uh oh!

bernardnormier left a comment

Choose a reason for hiding this comment

Uh oh!

bernardnormier Jul 8, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

externl commented Jul 8, 2026 •

edited

Loading